SecureClaw — Hardened Personal AI Agent Gateway

Version: 0.2.0 (Phase 2 — Core Agent Capabilities) Target: Apple Mac Mini M4 Pro · macOS 13+ · 64 GB Unified Memory

SecureClaw is a security-hardened personal AI agent gateway that addresses all documented vulnerabilities in OpenClaw while delivering full feature parity. It is designed for a single personal user managing sensitive data on an Apple Silicon Mac.

---

Current Status: Phase 2 Complete

Phase	Component	Status	Description
1	Touch ID / Secure Enclave auth	✅	Swift helper + Node.js wrapper
1	macOS Keychain integration	✅	keytar + CredentialBroker
1	TLS gateway (loopback only)	✅	Fastify + HTTPS, never 0.0.0.0
1	Universal rate limiting	✅	No localhost exemption (CVE mitigation)
1	JWT session tokens	✅	HS256, 15-min expiry, jti replay prevention
1	Passphrase fallback (Argon2id)	✅	For remote access without Touch ID
1	Encrypted config (AES-256-GCM)	✅	Keychain-protected key
1	Tamper-evident audit log	✅	Hash-chained, AES-256-GCM encrypted
1	Input sanitization	✅	Shell metachar stripping, prompt injection scanner
1	Origin validation (WebSocket)	✅	Strict allowlist, CVE-2026-25253 mitigation
2	iMessage channel	✅	AppleScript (send) + chat.db polling (receive)
2	WhatsApp channel	✅	Baileys library, personal account, QR pairing
2	Email channel	✅	IMAP/SMTP + Gmail OAuth 2.0
2	Agent Runtime (Ollama)	✅	qwen2.5:14b, tool-calling loop, trust tagging
2	Encrypted memory	✅	AES-256-GCM + BM25/vector hybrid search
2	Web Control UI	✅	Single-file HTML dashboard, real-time WebSocket

---

Security CVE Mitigations

CVE / Finding	Mitigation	Phase
CVE-2026-25253: WebSocket token exfiltration	No query-string auth; strict Origin validation	✅ 1
CVE-2026-25157 / 24763: Command injection	Parameterized execution; shell metachar sanitization	✅ 1
Localhost brute-force (no rate limiting)	Universal rate limiting, Touch ID unlock on mass failure	✅ 1
Auto-approval of localhost device pairings	Touch ID required for all pairings	✅ 1
Plaintext credential storage	All secrets in macOS Keychain, Credential Broker pattern	✅ 1
Supply chain (ClawHub malware)	No external marketplace; manual install + signing	Phase 3
Prompt injection via external content	Content trust tagging; pattern filtering + confirmation queue	✅ 1+2
Gateway on 0.0.0.0	Loopback-only binding; pf firewall rules	✅ 1
No audit logging	Tamper-evident hash-chained encrypted audit log	✅ 1
Memory/state poisoning	AES-256-GCM + GCM auth tag verification on every read	✅ 2

---

Prerequisites

• macOS 13.0+ (Ventura) — Sequoia recommended
• Apple M4 Pro with Touch ID enabled
• Xcode Command Line Tools: xcode-select --install
• Homebrew: https://brew.sh
• Node.js 20+: brew install node@20
• Ollama: https://ollama.ai/download — install and run ollama pull qwen2.5:14b && ollama pull nomic-embed-text
• Tailscale: https://tailscale.com/download/mac (for remote access)

---

Installation

1. Clone the repository

git clone <your-repo-url> secureclaw
cd secureclaw

2. Run setup

npm run setup

This will:

• Check all prerequisites
• Create ~/SecureClaw/ directory structure (with chmod 700)
• Generate a TLS certificate for localhost + Tailscale hostname
• Build the Swift Touch ID helper
• Generate and store encryption keys in your macOS Keychain (Touch ID required)
• Install Node.js dependencies and build TypeScript
• Configure macOS pf firewall rules (requires sudo)

3. Review your .env file

# Set your Tailscale hostname if not auto-detected:
SECURECLAW_TAILSCALE_HOSTNAME=your-mac-mini.tail-xxxx.ts.net

4. Trust the TLS certificate (optional, removes browser warning)

bash scripts/trust-cert.sh

5. Pull Ollama models

ollama pull qwen2.5:14b
ollama pull nomic-embed-text

6. Start SecureClaw

# Development mode (tsx, with hot reload):
npm run dev

# Production mode:
npm start

7. Open the Web Control Panel

Navigate to: https://localhost:18789/ui/control-panel.html

Authenticate with your passphrase (or Touch ID on the Mac) when prompted.

8. Install as a Launch Agent (auto-start at login)

nano scripts/launchd-agent.plist   # update paths
cp scripts/launchd-agent.plist ~/Library/LaunchAgents/com.secureclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/com.secureclaw.gateway.plist

---

Usage

Gateway URLs

After starting, SecureClaw runs at:

• Local: https://localhost:18789/
• Control Panel: https://localhost:18789/ui/control-panel.html
• Remote (Tailscale): https://your-mac-mini.tail-xxxx.ts.net:18789/

Authentication

Touch ID (primary):

curl -k -X POST https://localhost:18789/auth/touchid \
  -H "Content-Type: application/json" \
  -d '{"reason": "SecureClaw access"}'
# → prompts Touch ID on Mac, returns { "sessionToken": "...", "refreshToken": "..." }

Passphrase (remote access fallback):

curl -k -X POST https://localhost:18789/auth/passphrase \
  -H "Content-Type: application/json" \
  -d '{"passphrase": "your-passphrase"}'

WebSocket:

// Token MUST be in the Authorization header — never in the URL
const ws = new WebSocket('wss://localhost:18789/ws', [], {
  headers: { 'Authorization': `Bearer ${sessionToken}` }
});

iMessage Setup

iMessage receive requires Full Disk Access for the Node.js binary:

1. System Settings → Privacy & Security → Full Disk Access
2. Add the Node.js binary (e.g. /opt/homebrew/bin/node)
3. Restart SecureClaw

WhatsApp Setup

On first start, a QR code will be printed to the terminal. Scan it with WhatsApp on your phone (Linked Devices → Link a Device). Auth state is persisted for future starts.

Email Setup

Store Gmail credentials in Keychain (setup.sh handles this interactively):

# OAuth 2.0 access token (preferred):
security add-generic-password -s "com.secureclaw.gateway" -a "channel-email-gmail-access-token" -w "your-token"

# Or Gmail App Password:
security add-generic-password -s "com.secureclaw.gateway" -a "channel-email-app-password" -w "user@gmail.com:app-password"

Health check

curl -k https://localhost:18789/health
# → { "status": "ok", "version": "0.2.0" }

---

Web Control Panel

The Control Panel is served at /ui/control-panel.html. Features:

• Chat — Direct conversation with the agent. Supports multi-turn sessions across all channels.
• Confirmations — Review and approve/reject tool calls triggered by external content (emails, WhatsApp messages). These are queued and never auto-executed.
• Channels — Live status of iMessage, WhatsApp, Email channels (connected/disconnected, message counts).
• Memory — Semantic search across your encrypted memory. Results show category, match type (BM25/vector/hybrid), and similarity score.
• Audit Log — Real-time tamper-evident audit log viewer with filtering by event type and source. Click any row for full metadata. "Verify Chain" re-hashes the entire log chain and reports integrity status.

---

Running Tests

# Run all tests
npm test

# Run with coverage (security-critical modules require 100%)
npm run test:coverage

---

Project Structure

secureclaw/
├── src/
│   ├── core/
│   │   ├── auth/            # Authentication: TouchIDService, AuthService, RateLimiter
│   │   ├── audit/           # Tamper-evident audit logger
│   │   ├── keychain/        # macOS Keychain: KeychainService, CredentialBroker
│   │   ├── config/          # Encrypted configuration
│   │   └── gateway/         # TLS gateway: Gateway, InputSanitizer
│   ├── agent/
│   │   ├── AgentRuntime.ts  # LLM reasoning engine + tool-calling loop
│   │   ├── OllamaClient.ts  # Ollama HTTP client (qwen2.5:14b)
│   │   ├── ToolRegistry.ts  # Tool management + confirmation queue
│   │   └── tools/
│   │       └── CoreTools.ts # File, web search, memory tools
│   ├── channels/
│   │   ├── base/            # BaseChannel interface + ChannelManager
│   │   ├── imessage/        # iMessage via AppleScript + chat.db polling
│   │   ├── whatsapp/        # WhatsApp via Baileys
│   │   └── email/           # IMAP/SMTP + Gmail OAuth 2.0
│   ├── memory/
│   │   └── MemoryService.ts # AES-256-GCM memory + BM25/vector search
│   ├── ui/
│   │   └── control-panel.html  # Web Control Panel (single-file)
│   ├── types/               # Shared TypeScript types
│   └── index.ts             # Entry point
├── swift-helpers/           # Swift Touch ID / Secure Enclave helper
├── tests/                   # Unit tests (Phase 1 security-critical)
├── scripts/                 # Setup, TLS generation, launchd plist
├── certs/                   # Generated TLS certificates (git-ignored)
└── .env                     # Non-secret configuration (git-ignored)

---

Phase 3 Roadmap

Phase 3 will add:

1. Plugin sandbox manager — Signed, scoped plugins in a restricted Node.js worker context; no raw credential access
2. Apple Health integration — HealthKit bridge for fitness and health data queries
3. Financial document processing — Local OCR + categorization of bank/card statements
4. Calendar & reminders — EventKit bridge (read/write)
5. Security audit — Penetration testing and OWASP Mobile Top 10 compliance review

---

Security Notes

Keychain storage: All secrets are stored exclusively in the macOS Keychain, protected by the Secure Enclave. No secrets ever appear in .env, config files, logs, or URLs.

Loopback-only binding: The gateway binds to 127.0.0.1:18789 only. Remote access is exclusively through Tailscale's WireGuard tunnel. The pf firewall rules provide defense-in-depth.

Audit log integrity: The audit log uses a SHA-256 hash chain. Any modification to an existing entry breaks all subsequent entries' chain verification. Run npm test or click "Verify Chain" in the Control Panel.

External content trust: Any message arriving via email, WhatsApp, or iMessage is tagged external. Tool calls triggered by external content go to the Confirmation Queue in the Control Panel — they are never auto-executed.

Memory encryption: Every memory file on disk is AES-256-GCM encrypted with a key derived (HKDF) from the root Keychain key. The GCM auth tag is verified on every read — any tampering is detected immediately and logged as an INTEGRITY_FAILURE.

No telemetry: SecureClaw collects zero telemetry. There are no "phone home" connections of any kind.

---

Reporting Security Issues

As this is a personal, private tool, report security issues by creating a private note in your SecureClaw workspace or contacting the owner directly.